home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.3 Development Libraries / SGI IRIX 6.3 Development Libraries.iso / dist / dist6.3 / ViewKit_dev.idb / usr / include / Vk / VkCutPaste.h.z / VkCutPaste.h
C/C++ Source or Header  |  1996-09-20  |  15KB  |  434 lines
  1. ////////////////////////////////////////////////////////////////////////
  2. //
  3. // VkCutPaste.h
  4. //
  5. // This is the API for the Young/Wilson CutPasteDragDrop class to solve all
  6. // your Cut & Paste needs.
  7. //
  8. // ---------------------------------------------------------------------
  9. //
  10. // Copyright 1995, Silicon Graphics, Inc.
  11. // ALL RIGHTS RESERVED
  12. //
  13. // UNPUBLISHED -- Rights reserved under the copyright laws of the United
  14. // States.   Use of a copyright notice is precautionary only and does not
  15. // imply publication or disclosure.
  16. //
  17. // U.S. GOVERNMENT RESTRICTED RIGHTS LEGEND:
  18. // Use, duplication or disclosure by the Government is subject to restrictions
  19. // as set forth in FAR 52.227.19(c)(2) or subparagraph (c)(1)(ii) of the Rights
  20. // in Technical Data and Computer Software clause at DFARS 252.227-7013 and/or
  21. // in similar or successor clauses in the FAR, or the DOD or NASA FAR
  22. // Supplement.  Contractor/manufacturer is Silicon Graphics, Inc.,
  23. // 2011 N. Shoreline Blvd. Mountain View, CA 94039-7311.
  24. //
  25. // THE CONTENT OF THIS WORK CONTAINS CONFIDENTIAL AND PROPRIETARY
  26. // INFORMATION OF SILICON GRAPHICS, INC. ANY DUPLICATION, MODIFICATION,
  27. // DISTRIBUTION, OR DISCLOSURE IN ANY FORM, IN WHOLE, OR IN PART, IS STRICTLY
  28. // PROHIBITED WITHOUT THE PRIOR EXPRESS WRITTEN PERMISSION OF SILICON
  29. // GRAPHICS, INC.
  30. //
  31. ////////////////////////////////////////////////////////////////////////
  32.  
  33. /* $Id: VkCutPaste.h,v 1.9 1995/11/08 20:31:43 dyoung Exp $ */
  34.  
  35. #ifndef VK_CUT_PASTE_H_
  36. #define VK_CUT_PASTE_H_
  37.  
  38. #include <X11/X.h>
  39. #include <X11/Intrinsic.h>
  40. #include <Vk/VkCallbackObject.h>
  41. #include <Vk/VkBase.h>
  42.  
  43.  
  44. //////////////////////////////////////////////////////////////////////////
  45. //                       Constants
  46. //////////////////////////////////////////////////////////////////////////
  47.  
  48. #define CUTPASTE_NORMAL_TYPE   0
  49. #define CUTPASTE_FILENAME_TYPE (1<<0)
  50. #define CUTPASTE_HIDDEN_TYPE  (1<<1)
  51.  
  52.  
  53. //////////////////////////////////////////////////////////////////////////
  54. //                       Prototype Definitions 
  55. //////////////////////////////////////////////////////////////////////////
  56.  
  57. //////////////////////////////////////////////////////////////////////////
  58. //
  59. // ConvertProc:
  60. //
  61. // Prototype definition for conversion routines registered with
  62. // registerConverter().
  63. //
  64. // These routines are called when a conversion to go from 'srcTarget' to
  65. // 'dstTarget' is required.  Note that numSrcBytes and numDstBytes are
  66. // in bytes, not 'format based units' (as in XtSelectionCallbackProc).
  67. //
  68. // The ConvertProc must set the dst and numDstBytes parameters if the
  69. // conversion was successful.
  70. //
  71. // The ConvertProc must return True if the conversion was successful,
  72. // and False otherwise.
  73. //
  74. //////////////////////////////////////////////////////////////////////////
  75.  
  76. typedef Boolean (*ConvertProc)(Widget w, Atom selection, void *clientData,
  77.   Atom srcTarget, XtPointer src, unsigned long numSrcBytes, 
  78.   Atom dstTarget, XtPointer *dst, unsigned long *numDstBytes);
  79.  
  80. ////////
  81. //
  82. // CanConvertProc
  83. //
  84. ////////
  85.  
  86. typedef Boolean (*CanConvertProc)(Widget w, Atom selection, void *clientData,
  87.   Atom srcTarget, XtPointer src, unsigned long numSrcBytes, Atom dstTarget);
  88.  
  89.  
  90. //////////////////////////////////////////////////////////////////////////
  91. //
  92. // DestroyProc:
  93. //
  94. // Prototype definition for providing a client side hook to cleanup
  95. // "related data".  For example, if you make an SGI_RGBIMAGE_FILE available
  96. // to other clients then you have created a file (let's say "/usr/tmp/foo.rgb").
  97. // When the data is no longer needed, the destroy proc is called with the 
  98. // filename, and you need to delete the file.  (You DO NOT free the filename in
  99. // this DestroyProc, since that is free'ed automatically by the VkCutPaste 
  100. // library.)
  101. //
  102. //////////////////////////////////////////////////////////////////////////
  103.  
  104. typedef void (*DestroyProc)(Widget w, Atom selection, Atom target, 
  105.     XtPointer data, unsigned long numBytes, void *clientData);
  106.  
  107.  
  108. //////////////////////////////////////////////////////////////////////////
  109. //
  110. // LoseSelectionProc
  111. //
  112. // Client side callback which is called when the X Windows selection
  113. // ownership is "lost".  This means some either this client has "disowned"
  114. // the selection (by calling clear()), or another client has obtained
  115. // selection ownership.
  116. //
  117. //////////////////////////////////////////////////////////////////////////
  118.  
  119. typedef void (*LoseSelectionProc)(Widget w, Atom selection, void *clientData);
  120.  
  121.  
  122. //////////////////////////////////////////////////////////////////////////
  123. //
  124. // DropSiteCallbackProc:
  125. //
  126. // Client side callback which is called when a drop operation has been
  127. // successfully completed.
  128. //
  129. // target will be the first target in the list of targets (passed to
  130. // the registerDropSite() call) which was available during the drop.
  131. //
  132. //////////////////////////////////////////////////////////////////////////
  133.  
  134. typedef void (*DropSiteCallbackProc)(Widget w, Atom target,
  135.   XtPointer data, unsigned long numBytes, int x, int y, void *clientData);
  136.  
  137.  
  138. //////////////////////////////////////////////////////////////////////////
  139. //
  140. // DragCallbackProc:
  141. //
  142. // Client side callback which is called when a drag occurs over the drop site
  143. //
  144. // target will be the target which will eventually be dropped if and when the
  145. // user let's go of the mouse button
  146. //
  147. //////////////////////////////////////////////////////////////////////////
  148.  
  149. typedef void (*DragCallbackProc)(Widget w, Atom target, int reason, 
  150.   int x, int y, void *clientData);
  151.  
  152.  
  153. //////////////////////////////////////////////////////////////////////////
  154. //
  155. // DragAwayCallbackProc:
  156. //
  157. // Client side callback which is called when the drag away has been completed.
  158. //
  159. // The result is whether the drag was successful or not.
  160. //
  161. //////////////////////////////////////////////////////////////////////////
  162.  
  163. typedef void (*DragAwayCallbackProc)(Widget w, Boolean result,void *clientData);
  164.  
  165.  
  166. //////////////////////////////////////////////////////////////////////////
  167. //
  168. // ImportCallbackProc:
  169. //
  170. // Client side callback which is called when a import() call has data
  171. // to return.
  172. //
  173. // type will be the first target in the list of targets (passed in
  174. // the import() call) which was available from the source client.
  175. //
  176. //////////////////////////////////////////////////////////////////////////
  177.  
  178. typedef void (*ImportCallbackProc)(Widget w, Atom target, XtPointer data, 
  179.   unsigned long numBytes, void *clientData);
  180.  
  181.  
  182. // extern declaration so we don't have to include _VkCutPasteMgr.h
  183. class _VkCutPasteMgr;
  184.  
  185. class VkCutPaste : public VkCallbackObject, public VkBase
  186. {
  187.   public:
  188.     VkCutPaste(Widget w);
  189.     ~VkCutPaste();
  190.  
  191.     //////////////////////////////////////////////////////////////////////
  192.     //////////////// Simple Cut/Paste Export API /////////////////////////
  193.     //////////////////////////////////////////////////////////////////////
  194.  
  195.     ////////
  196.     //
  197.     // putReference():
  198.     //
  199.     //   Places a reference to the data onto the private clipboard specified
  200.     //   by 'selection'.
  201.     //
  202.     //   The pointer MUST remain valid until the next 'clear()' call,
  203.     //   or until the data is explicitly removed via 'remove()'.
  204.     //
  205.     ////////
  206.  
  207.     virtual Boolean putReference(Atom selection, Atom target,
  208.                  XtPointer data, unsigned long numBytes);
  209.  
  210.     virtual Boolean putReference(Atom selection, const char *targetName,
  211.                  XtPointer data, unsigned long numBytes);
  212.     
  213.     ////////
  214.     //
  215.     // putCopy():
  216.     //
  217.     //   Copies the data onto the private clipboard specified by 'selection'.
  218.     //   The data is managed by the VkCutPaste class, and does NOT need to be
  219.     //   explicitly removed via 'remove()'.
  220.     //
  221.     ////////
  222.  
  223.     virtual Boolean putCopy(Atom selection, Atom target, 
  224.                 XtPointer data, unsigned long numBytes);
  225.     
  226.     virtual Boolean putCopy(Atom selection, const char *targetName, 
  227.                 XtPointer data, unsigned long numBytes);
  228.     
  229.     ////////
  230.     //
  231.     // export():
  232.     //
  233.     // Exports the current contents of the private clipboard.  This
  234.     // routine will call XtOwnSelection().
  235.     //
  236.     // If you pass a 'time' of 'CurrentTime', the timestamp from the last
  237.     // X Event processed will be used.
  238.     //
  239.     ////////
  240.  
  241.     virtual Boolean export(Atom selection, Time time = CurrentTime);
  242.  
  243.  
  244.     ////////
  245.     //
  246.     // clear():
  247.     //
  248.     // Clears the private clipboard, and the export target list.
  249.     // Calls XtDisownSelection.
  250.     //
  251.     // If you pass a 'time' of 'CurrentTime', the timestamp from the last
  252.     // X Event processed will be used.
  253.     //
  254.     ////////
  255.  
  256.     virtual void clear(Atom selection, Time time = CurrentTime);
  257.  
  258.  
  259.     ////////
  260.     //
  261.     // remove():
  262.     //
  263.     // Removes the data specified by 'target' from the private clipboard
  264.     // specified by 'selection', and from the export list if 'export()'
  265.     // has been called.
  266.     //
  267.     // Clients must call 'remove()' on data that was placed on the
  268.     // private clipboard when using the 'putReference()' call if the
  269.     // data pointer becomes invalid.
  270.     //
  271.     ////////
  272.  
  273.     virtual Boolean remove(Atom selection, Atom target);
  274.  
  275.  
  276.     //////////////////////////////////////////////////////////////////////
  277.     //////////////// Simple Cut/Paste Import API /////////////////////////
  278.     //////////////////////////////////////////////////////////////////////
  279.  
  280.     ////////
  281.     //
  282.     // importImmediate():
  283.     //
  284.     //   Immediately returns the first item it can successfully import from the
  285.     //   prioritized "interestList".  It returns NULL if no valid data 
  286.     //   is available that fits the interestList description.  Clients must
  287.     //   free returned data with XtFree(). 
  288.     //
  289.     ////////
  290.  
  291.     virtual XtPointer importImmediate(Atom selection, Atom *interestList, 
  292.                       int interestListLen, Atom *targetRet,
  293.                       unsigned long *numBytesRet, 
  294.                       Time theTime = CurrentTime);
  295.     
  296.  
  297.     ////////
  298.     //
  299.     // import():
  300.     //
  301.     //   This call is exactly like "importImmediate()" above, but it uses a
  302.     //   callback to alert the program when the data has arrived.  This is 
  303.     //   useful if the client has a custom event loop and needs to do other 
  304.     //   tasks while waiting for the data to arrive.
  305.     //
  306.     ////////
  307.  
  308.     virtual void import(Atom selection, Atom *interestList, int interestListLen,
  309.             ImportCallbackProc proc, void *clientData = NULL, 
  310.             Time theTime = CurrentTime);
  311.     
  312.  
  313.     //////////////////////////////////////////////////////////////////////
  314.     //////////////// Simple Drag/Drop API ////////////////////////////////
  315.     //////////////////////////////////////////////////////////////////////
  316.  
  317.     ////////
  318.     //
  319.     // registerDropSite():
  320.     //
  321.     //   Registers a widget, so that if anyone drops something on this widget
  322.     //   that is found in the prioritized "interestList", the callback is
  323.     //   invoked.
  324.     //
  325.     ////////
  326.  
  327.     virtual Boolean registerDropSite(Widget w, Atom *interestList, 
  328.                      int interestListLen,
  329.                      DropSiteCallbackProc proc,
  330.                      void *clientData = NULL);
  331.  
  332.  
  333.     ////////
  334.     //
  335.     // dragAwayCopy():
  336.     //   
  337.     //   Call this, and a copy of the data immediately begins being "dragged".
  338.     //   The program can free the data after this call, and this one call is 
  339.     //   all that needs to be done for a successful drag and drop operation.
  340.     //
  341.     ////////
  342.  
  343.     virtual Widget dragAwayCopy(Widget w, XEvent *xev,
  344.                 Atom target, XtPointer data,
  345.                 unsigned long numBytes,
  346.                 DragAwayCallbackProc dragAwayProc = NULL,
  347.                 void *clientData = NULL);
  348.     
  349.     virtual Widget dragAwayCopy(Widget w, XEvent *xev,
  350.                 const char *targetName, XtPointer data,
  351.                 unsigned long numBytes,
  352.                 DragAwayCallbackProc dragAwayProc = NULL,
  353.                 void *clientData = NULL);
  354.     
  355.  
  356.     //////////////////////////////////////////////////////////////////////
  357.     /////////////// More advanced utility functions //////////////////////
  358.     //////////////////////////////////////////////////////////////////////
  359.     virtual unsigned long getVersion();
  360.     virtual Widget getWidget();
  361.     Atom   clipboardAtom();
  362.     Atom   primaryAtom();
  363.  
  364.     virtual void registerDataType(Atom target, Atom type, int format, 
  365.                   unsigned long flags = CUTPASTE_NORMAL_TYPE,
  366.                   DestroyProc = NULL, 
  367.                   void *clientData = NULL);
  368.     virtual void registerDataType(const char *targetName, const char *typeName, 
  369.                   int format,
  370.                   unsigned long flags = CUTPASTE_NORMAL_TYPE, 
  371.                   DestroyProc = NULL, void *clientData = NULL);
  372.     virtual Boolean getDataTypeInfo(Atom target, Atom *type, int *format, 
  373.                     unsigned long *flags);
  374.     virtual void registerConverter(Atom from, Atom to, ConvertProc, 
  375.                    CanConvertProc = NULL,
  376.                    void *clientData = NULL);
  377.     virtual void registerConverter(const char *fromName, const char *toName, 
  378.                    ConvertProc, CanConvertProc = NULL,
  379.                    void *clientData = NULL);
  380.     virtual Boolean unregisterDropSite(Widget);
  381.     virtual Boolean registerLoseSelection(Atom selection,
  382.                       LoseSelectionProc loseSelProc,
  383.                       void *clientData);
  384.     virtual void setTransactionsTimeout(unsigned long numSeconds);
  385.     virtual void activateHelpfulConverters();
  386.     virtual Boolean isOwnedByMe(Atom selection);
  387.     virtual Boolean isOwnedByLocalHost(Atom selection);
  388.     virtual Time getXServerTime();  // invokes a round trip to X-Server
  389.     virtual Boolean getFilenamesFromSGI_ICON(char *sgiIconData, 
  390.                          unsigned long numBytes,
  391.                          char ***fileNameArrayRet,
  392.                          int *numFilesRet);
  393.     virtual void freeFilenamesFromSGI_ICON(char **fileNameArray, int numFiles);
  394.     
  395.     virtual Widget dragAwayCopyExtended(Widget w, XEvent *xev,
  396.                     Atom *targetList, XtPointer *dataList,
  397.                     unsigned long *lenList,
  398.                     int numDragItems,
  399.                     DragAwayCallbackProc dragAwayProc = NULL, 
  400.                     void *clientData = NULL,
  401.                     ArgList args = NULL, int numArgs = 0);
  402.     
  403.     virtual Boolean registerDropSiteExtended(Widget w,
  404.                          Atom *interestList, int interestListLen,
  405.                          DropSiteCallbackProc proc,
  406.                          DragCallbackProc dragProc = NULL, 
  407.                          void *clientData = NULL,
  408.                          Arg *args = NULL, int n = 0);
  409.  
  410.  
  411.     //////////////////////////////////////////////////////////////////////
  412.     /////////////// Local retrieval of the "clipboard contents" //////////
  413.     /////////////// NOT X Selections based!!!                   //////////
  414.     //////////////////////////////////////////////////////////////////////
  415.     virtual Boolean getLocalReference(Atom, int,  Atom *, XtPointer *, 
  416.       unsigned long *);
  417.     virtual Boolean getLocalTypeReference(Atom, Atom, XtPointer *, 
  418.       unsigned long *);
  419.  
  420.     //////////////////////////////////////////////////////////////////////
  421.     //////// Advanced routines probably (?) not needed by anyone /////////
  422.     //////////////////////////////////////////////////////////////////////
  423.     virtual Boolean registerSite(Atom selection);
  424.     virtual Boolean unregisterSite(Atom selection);
  425.   
  426.    protected:
  427.  
  428.     VkCutPaste();
  429.  
  430.     _VkCutPasteMgr *cutPasteMgr;
  431. };
  432.  
  433. #endif // VK_CUT_PASTE_H_
  434.